Inside Macintosh: Open Transport /

Chapter 7 - Process Management

Using Process Management Functions

Most of the functions in this chapter are concerned with system and deferred tasks. Much of the processing for these two kinds of tasks is similar, so they are covered in the same section. There are two functions for notifying Open Transport that you are entering and leaving interrupt processing, and although these are associated with using deferred tasks, they are covered in a separate section. There is a brief section on the little-used functions for idling and delaying your computer. Finally, there is a section on how to write an application-defined process callback function that you can use when creating system and deferred tasks.

Using System and Deferred Tasks

To use system or deferred tasks with the Open Transport functions, you use a process callback function that defines the task you want executed at a scheduled system or deferred task time. When you call the Open Transport function that creates a system task with the OTCreateSystemTask function (or creates a deferred task with the OTCreateDeferredTask function), you pass a pointer to your process callback function so that Open Transport can call it at the specified time. You can also pass user-defined context information at this time. When Open Transport calls back your function, it passes back the context data you supplied when you created the task. For the 68000-family of Macintosh computers, Open Transport also restores the A5 world to what it was when you created the task.

The OTCreateSystemTask and OTCreateDeferredTask functions allocate a structure that defines the task you want executed. Upon completion, these functions return a reference by which you subsequently refer to the task in other system or deferred task functions.

Once you have created a task, you need to schedule it for execution. To do this, you use the OTScheduleSystemTask, the OTScheduleDeferredTask, or the OTScheduleInterruptTask function. You pass the task reference to the function (the stCookie or the dtCookie parameter), and Open Transport attempts to schedule the task. If a system task is scheduled successfully, it executes when the SystemTask function next executes; and if a deferred task is scheduled successfully, it executes as soon as possible after leaving the interrupt context.

However, because a system task can happen relatively slowly, enough time can elapse between scheduling and execution to let you cancel it before it runs. Deferred tasks happen too quickly to allow time for canceling tasks. If you use the OTCancelSystemTask function, you notify Open Transport not to execute the system task at the scheduled time. The reference is still valid, and you can choose to reschedule the task by using the OTScheduleSystemTask function again at any time.

You can also choose to reschedule a system or deferred task after it has executed successfully. You do this by using the OTScheduleSystemTask or the OTScheduleDeferredTask function again at any time. If you choose to reschedule a task, you reuse the same reference to the same task. This means that exactly the same task executes, which is useful for repetitive periodic tasks.

You can choose to destroy a task with the OTDestroySystemTask or the OTDestroyDeferredTask function. These functions make the task reference invalid and free any resources associated with the task. You can call these functions whenever it is no longer necessary to schedule a task, such as when it has been executed at its scheduled time and you have no plans to reschedule it for later use.

You can call the OTDestroySystemTask function to destroy a system task that is currently scheduled for execution. In this case, Open Transport cancels the system task before proceeding with the task's destruction.

If you try to destroy a scheduled deferred task with the OTDestroyDeferredTask function, the kEAgainErr error can occur. This is a rare situation that can only happen when you try to destroy the task from within an interrupt service routine or within another deferred task.

If you want to use a task after you have destroyed it, you must start from the beginning again by creating a new task with the OTCreateSystemTask or the OTCreateDeferredTask functions.

Entering and Leaving Interrupt Processing

There are some Open Transport functions that you can call at interrupt time, but you must be sure to notify Open Transport that you are doing so and notify Open Transport when you are done. The permitted functions are listed in
Table 7-1.

Table 7-1 Open Transport functions you can call at interrupt time

Function	Description
OTCanMakeSyncCall	Checks whether a synchronous call will fail
OTAllocMem	Allocates raw memory
OTFreeMem	Frees the memory allocated with OTAllocMem
OTEnterInterrupt	Prepares for an Open Transport function call during interrupt time
OTLeaveInterrupt	Concludes the processing of an Open Transport function call during interrupt time
OTScheduleSystemTask	Schedules a system task
OTCancelSystemTask	Cancels a system task
OTScheduleDeferredTask	Schedules a deferred task
OTScheduleInterruptTask	Schedules a deferred task

If you are at interrupt time and you want to call an Open Transport function, you must first call the OTEnterInterrupt function. You can then call one of the permitted functions. When you are done with calling Open Transport functions at interrupt time, you must call the OTLeaveInterrupt function. For example, you could execute these code statements in this sequence:

OTEnterInterrupt();
OTScheduleDeferredTask(dtCookie);
OTLeaveInterrupt();

The exception to this set of tasks is the OTScheduleInterruptTask function. If all you want to do is schedule a deferred task, you can use the OTScheduleInterruptTask function, which takes care of the OTEnterInterrupt and OTLeaveInterrupt functions for you.

WARNING

If you try to call an Open Transport function that is not permitted at interrupt time or if you do not use the OTEnterInterrupt and OTLeaveInterrupt functions, you will either get the OTBadSyncErr result code or crash your system, depending on the function you call.

Allocating and Freeing Raw Memory

Open Transport provides two interrupt-safe functions to allow you to allocate memory from the Open Transport memory pool.

You can use the OTAllocMem function to obtain raw memory. The memory is allocated from a pool that Open Transport has created on behalf of the client application. You need to use the OTAllocMem function to be able to access this memory. You need to use this function if you want to allocate memory within an interrupt. To deallocate this memory, use the OTFreeMem function with the pointer returned by the OTAllocMem function.

Idling or Delaying Your Computer

There are two little-used functions for idling or delaying your computer: OTIdle and OTDelay. The former function does not currently offer any practical use beyond providing compatibilty with existing code that already uses an idle function. The latter function is only included for compatibility with the UNIX sleep function and should not be used in your code for any other reason. Be sure not to include in any production code in your products.